generic
   type Pointer is private;
package v8.Class_Handle is
   type Handle_Object (<>) is tagged limited private;
   type Handle is access all Handle_Object;
   -- An object reference managed by the v8 garbage collector.
   --
   -- All objects returned from v8 have to be tracked by the garbage
   -- collector so that it knows that the objects are still alive.  Also,
   -- because the garbage collector may move objects, it is unsafe to
   -- point directly to an object.  Instead, all objects are stored in
   -- handles which are known by the garbage collector and updated
   -- whenever an object moves.  Handles should always be passed by value
   -- (except in cases like out-parameters) and they should never be
   -- allocated on the heap.
   --
   -- There are two types of handles: local and persistent handles.
   -- Local handles are light-weight and transient and typically used in
   -- local operations.  They are managed by HandleScopes.  Persistent
   -- handles can be used when storing objects across several independent
   -- operations and have to be explicitly deallocated when they're no
   -- longer used.
   --
   -- It is safe to extract the object stored in the handle by
   -- dereferencing the handle (for instance, to extract the Object-- from
   -- a Handle<Object>); the value will still be governed by a handle
   -- behind the scenes and the same rules apply to these values as to
   -- their handles.


   function Is_Empty (This : Handle_Object) return Boolean;

   procedure Clear (This : in out Handle_Object);

   function As_Object (this : Handle_Object) return Pointer;

   function As_Handle (this : access Handle_Object) return Handle;
   -- Contravariance

private
   type Handle_Object is tagged limited null record;

   function As_Handle (this : access Handle_Object) return Handle is (Handle (this));

end v8.Class_Handle;
